NestJS 概述与架构

import { Module } from '@nestjs/common';
import { Controller, Get } from '@nestjs/common';
import { Injectable } from '@nestjs/common';

@Injectable()
export class UserService {
  findAll() { return [{ id: 1, name: 'alice' }]; }
}

@Controller('users')
export class UserController {
  constructor(private readonly svc: UserService) {}
  @Get()
  findAll() { return this.svc.findAll(); }
}

@Module({ controllers: [UserController], providers: [UserService] })
export class UserModule {}

NestJS 最佳应用场景：
│
├──  场景一：前端团队规模较大
│   ├── 前端开发者数量 ≥ 后端开发者数量
│   ├── 前端团队已具备 Node.js 基础
│   └── 需要快速开发后端 API
│
├──  场景二：公司有 Node.js 开发先例
│   ├── 公司高层了解 Node.js 优势
│   ├── 已有相关技术栈积累
│   └── 更愿意加大投入
│
└──  场景三：独立开发者接私活
    ├── 不受团队约束
    ├── 自主选择技术栈
    └── 注重开发效率

//  场景一：WebSocket 实时应用
// NestJS 官方提供 @nestjs/websockets 支持
@WebSocketGateway()
export class ChatGateway {
  @SubscribeMessage('message')
  handleMessage(client: Socket, payload: string): string {
    return 'Hello world';
  }
}

//  场景二：快速上线项目
// NestJS CLI 快速生成项目结构
// $ nest new project-name
// $ nest g module users
// $ nest g controller users
// $ nest g service users

//  场景三：Serverless 微服务
// NestJS 支持微服务架构
@Injectable()
export class AppService {
  getData(): { message: string } {
    return { message: 'Welcome to nest-api!' };
  }
}

推动 NestJS 落地策略：
│
├──  第一步：成为技术布道者
│   ├── 学习并掌握 NestJS 核心
│   ├── 团队内分享技术优势
│   └── 组织技术分享会
│
├──  第二步：性能对比演示
│   ├── 编写 Java vs Node.js 性能测试案例
│   ├── 展示 NestJS 在高并发场景下的表现
│   └── 提供详细的性能测试报告
│
└──  第三步：实际项目验证
    ├── 在私活项目中使用 NestJS
    ├── 展示项目成果和开发效率
    └── 与团队成员分享实战经验

团队结构示例：
前端团队：2-3 人
后端团队：10+ 人

是否适合 NestJS？需要考虑：
├──  前端团队能否支撑所有前端项目？
├──  后端开发者是否涉及前端开发？
├──  配给前端的后端支持有多少？
└──  如果前端已满负荷，不建议增加后端工作

团队结构示例：
前端团队：10+ 人
后端团队：2-3 人

适合采用 NestJS：
├──  前端团队可分担后端开发压力
├──  降低后端招聘成本
├──  前后端技术栈统一，沟通成本低
└──  全栈开发能力提升

// ===== Java Spring Boot 示例 =====
@RestController
public class UserController {
    @GetMapping("/users")
    public List<User> getUsers() {
        // 数据库查询
        return userRepository.findAll();
    }
}

// ===== NestJS 示例 =====
@Controller('users')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get()
  async findAll(): Promise<User[]> {
    return this.userService.findAll();
  }
}

// 性能对比要点：
// 1. 开发效率：NestJS CLI 生成代码更快
// 2. 语言统一：前后端都使用 TypeScript
// 3. 性能表现：Node.js 在 I/O 密集型场景表现优异
// 4. 并发处理：Node.js 事件循环机制适合高并发

前端开发者能力矩阵：
│
├──  多端开发能力
│   ├── Web 应用
│   ├── 小程序（微信/支付宝/抖音）
│   ├── 移动端 APP（React Native/Flutter）
│   └── 桌面应用（Electron/Tauri）
│
├──  后端开发能力（掌握 NestJS）
│   ├── RESTful API 设计
│   ├── 数据库设计与管理
│   ├── 微服务架构
│   └── GraphQL API
│
└──  工程化能力
    ├── 构建工具（Vite/Webpack）
    ├── CI/CD 流程
    ├── 性能优化
    └── 架构设计

// ===== NestJS 3.x - 11.x 核心用法稳定性对比 =====

//  装饰器用法一直保持稳定
@Controller('users')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get()
  findAll() {
    return this.userService.findAll();
  }
}

//  模块定义方式稳定
@Module({
  imports: [TypeOrmModule.forFeature([User])],
  controllers: [UserController],
  providers: [UserService],
})
export class UserModule {}

//  依赖注入方式稳定
@Injectable()
export class UserService {
  constructor(
    @InjectRepository(User)
    private userRepository: Repository<User>,
  ) {}

  async findAll(): Promise<User[]> {
    return this.userRepository.find();
  }
}

// 版本更新重点：
// - 性能优化
// - Bug 修复
// - 新功能添加
// - 核心API保持向后兼容

项目维护成本对比：
│
├── Java/Spring 项目
│   ├──  生态成熟，文档完善
│   ├──  需要专业 Java 开发者
│   ├──  前后端技术栈分离
│   └──  维护成本：中等
│
├── Go 项目
│   ├──  性能优异
│   ├──  生态相对较新
│   ├──  需要专业 Go 开发者
│   └──  维护成本：中等
│
└── NestJS 项目
    ├──  前后端技术栈统一（TypeScript）
    ├──  前端开发者可快速上手
    ├──  架构清晰，易于维护
    └──  维护成本：相当

# 1. 全局安装 NestJS CLI
npm install -g @nestjs/cli

# 2. 创建新项目
nest new nest-api
# 选择 pnpm 作为包管理器

# 3. 启动开发服务器
cd nest-api
pnpm run start:dev

# 4. 生成 CRUD 模块（快速开发）
nest g resource users
# 选择 REST API
# 选择 Yes 生成 CRUD 入口点

nest-api/
├── src/
│   ├── main.ts              # 应用入口
│   ├── app.module.ts        # 根模块
│   ├── users/               # 用户模块（自动生成）
│   │   ├── dto/             # 数据传输对象
│   │   ├── entities/        # 实体定义
│   │   ├── users.controller.ts   # 控制器
│   │   ├── users.module.ts       # 模块
│   │   └── users.service.ts      # 服务
│   └── ...
├── test/                    # 测试文件
├── nest-cli.json            # NestJS CLI 配置
├── tsconfig.json            # TypeScript 配置
└── package.json             # 项目依赖

// ===== main.ts - 应用启动文件 =====
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  // 配置全局前缀
  app.setGlobalPrefix('api');
  
  // 启用 CORS（前后端分离必备）
  app.enableCors();
  
  await app.listen(3000);
  console.log('Application is running on: http://localhost:3000/api');
}
bootstrap();

// ===== app.module.ts - 根模块 =====
import { Module } from '@nestjs/common';
import { UsersModule } from './users/users.module';

@Module({
  imports: [UsersModule],
  controllers: [],
  providers: [],
})
export class AppModule {}

// ===== users.controller.ts - 控制器（处理路由） =====
import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }

  @Get()
  findAll() {
    return this.usersService.findAll();
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.usersService.findOne(+id);
  }
}

// ===== users.service.ts - 服务（业务逻辑） =====
import { Injectable } from '@nestjs/common';
import { CreateUserDto } from './dto/create-user.dto';

@Injectable()
export class UsersService {
  private users = [];

  create(createUserDto: CreateUserDto) {
    const user = {
      id: Date.now(),
      ...createUserDto,
    };
    this.users.push(user);
    return user;
  }

  findAll() {
    return this.users;
  }

  findOne(id: number) {
    return this.users.find(user => user.id === id);
  }
}

// ===== dto/create-user.dto.ts - 数据传输对象 =====
export class CreateUserDto {
  name: string;
  email: string;
  age: number;
}

# 安装 TypeORM 和数据库驱动
pnpm add @nestjs/typeorm typeorm mysql2

// ===== app.module.ts - 配置数据库连接 =====
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { UsersModule } from './users/users.module';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'mysql',
      host: 'localhost',
      port: 3306,
      username: 'root',
      password: 'password',
      database: 'test',
      entities: [],
      synchronize: true, // 生产环境设为 false
    }),
    UsersModule,
  ],
})
export class AppModule {}

// ===== users/entities/user.entity.ts - 实体定义 =====
import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @Column()
  email: string;

  @Column()
  age: number;
}

// ===== users.module.ts - 注册实体 =====
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { UsersService } from './users.service';
import { UsersController } from './users.controller';
import { User } from './entities/user.entity';

@Module({
  imports: [TypeOrmModule.forFeature([User])],
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

// ===== users.service.ts - 使用数据库 =====
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { User } from './entities/user.entity';
import { CreateUserDto } from './dto/create-user.dto';

@Injectable()
export class UsersService {
  constructor(
    @InjectRepository(User)
    private userRepository: Repository<User>,
  ) {}

  create(createUserDto: CreateUserDto): Promise<User> {
    const user = this.userRepository.create(createUserDto);
    return this.userRepository.save(user);
  }

  findAll(): Promise<User[]> {
    return this.userRepository.find();
  }

  async findOne(id: number): Promise<User> {
    return this.userRepository.findOne({ where: { id } });
  }
}

学习路径：
│
├──  第一阶段：基础掌握（1-2 周）
│   ├── TypeScript 高级语法
│   ├── NestJS 核心概念：模块、控制器、服务
│   └── 依赖注入与装饰器
│
├──  第二阶段：实战练习（2-3 周）
│   ├── RESTful API 开发
│   ├── 数据库集成（TypeORM/Prisma）
│   └── 用户认证与授权
│
└──  第三阶段：进阶应用（3-4 周）
    ├── 微服务架构
    ├── GraphQL API
    ├── WebSocket 实时通信
    └── 部署与 DevOps

Node.js Web 框架演进史：
│
├── 2009 - Express
│   └── 第一个流行的 Node.js Web 框架
│
├── 2013 - Koa
│   └── Express 原班人马打造，更轻量、现代化
│
├── 2016 - Egg.js
│   └── 阿里出品，企业级框架，基于 Koa
│
└── 2017 - NestJS
    └── Angular 风格，TypeScript 优先，企业级架构

Express 特点：
│
├──  优势
│   ├── 生态最丰富，中间件众多
│   ├── 文档完善，社区活跃
│   ├── 灵活自由，无强制架构
│   └── 学习成本低，上手快
│
└──  劣势
    ├── 无 TypeScript 原生支持
    ├── 回调地狱（老版本）
    ├── 缺乏架构指导
    └── 大型项目难以维护

// ===== Express 基础示例 =====
const express = require('express');
const app = express();

// 中间件：解析 JSON
app.use(express.json());

// 路由定义
app.get('/', (req, res) => {
  res.send('Hello World');
});

app.get('/users', (req, res) => {
  res.json([
    { id: 1, name: '张三' },
    { id: 2, name: '李四' }
  ]);
});

app.post('/users', (req, res) => {
  const { name, email } = req.body;
  // 业务逻辑混在路由中
  const newUser = { id: Date.now(), name, email };
  res.status(201).json(newUser);
});

// 启动服务
app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

//  问题：
// 1. 缺乏分层，业务逻辑与路由耦合
// 2. 无依赖注入，需手动管理依赖
// 3. 无类型检查，容易出错

Koa 特点：
│
├──  优势
│   ├── 更轻量，核心仅 550 行代码
│   ├── async/await 支持，代码更优雅
│   ├── 洋葱模型中间件，控制流清晰
│   └── 无捆绑中间件，自由选择
│
└──  劣势
    ├── 功能太少，需自己实现路由等
    ├── 生态不如 Express 丰富
    ├── 无架构指导
    └── TypeScript 支持需配置

// ===== Koa 基础示例 =====
const Koa = require('koa');
const Router = require('koa-router');
const bodyParser = require('koa-bodyparser');

const app = new Koa();
const router = new Router();

// 中间件：洋葱模型示例
app.use(async (ctx, next) => {
  console.log('第一层中间件 - 开始');
  await next();
  console.log('第一层中间件 - 结束');
});

app.use(async (ctx, next) => {
  console.log('第二层中间件 - 开始');
  await next();
  console.log('第二层中间件 - 结束');
});

// 解析请求体
app.use(bodyParser());

// 路由定义
router.get('/', async (ctx) => {
  ctx.body = 'Hello World';
});

router.get('/users', async (ctx) => {
  ctx.body = [
    { id: 1, name: '张三' },
    { id: 2, name: '李四' }
  ];
});

router.post('/users', async (ctx) => {
  const { name, email } = ctx.request.body;
  const newUser = { id: Date.now(), name, email };
  ctx.status = 201;
  ctx.body = newUser;
});

// 注册路由
app.use(router.routes()).use(router.allowedMethods());

// 启动服务
app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

//  优点：洋葱模型清晰，async/await 优雅
//  问题：需自己搭建架构，缺乏分层

请求 → 中间件1 → 中间件2 → 中间件3 → 路由处理
                                              ↓
响应 ← 中间件1 ← 中间件2 ← 中间件3 ← 业务逻辑

执行顺序：
1. 请求进入中间件1
2. 调用 next() 进入中间件2
3. 调用 next() 进入中间件3
4. 调用 next() 进入路由处理
5. 路由处理完成，返回中间件3
6. 中间件3 完成，返回中间件2
7. 中间件2 完成，返回中间件1
8. 中间件1 完成，响应客户端

Egg.js 特点：
│
├──  优势
│   ├── 企业级架构，开箱即用
│   ├── 约定优于配置，规范统一
│   ├── 插件机制丰富
│   ├── 中文文档完善（阿里团队）
│   └── 内置安全、日志等功能
│
└──  劣势
    ├── TypeScript 支持不佳（需 Babel 编译）
    ├── 基于 CommonJS 规范，现代化不足
    ├── 学习成本较高（约定多）
    └── 性能略有损耗（封装层多）

// ===== Egg.js 项目结构 =====
egg-project/
├── app/
│   ├── controller/          # 控制器
│   │   └── home.js
│   ├── service/             # 服务层
│   │   └── user.js
│   ├── middleware/          # 中间件
│   ├── router.js            # 路由配置
│   └── extend/              # 扩展
├── config/
│   ├── config.default.js    # 配置文件
│   └── plugin.js            # 插件配置
└── package.json

// ===== app/router.js - 路由配置 =====
module.exports = app => {
  const { router, controller } = app;
  router.get('/', controller.home.index);
  router.get('/users', controller.user.list);
  router.post('/users', controller.user.create);
};

// ===== app/controller/home.js - 控制器 =====
const Controller = require('egg').Controller;

class HomeController extends Controller {
  async index() {
    const { ctx } = this;
    ctx.body = 'Hello World';
  }
}

module.exports = HomeController;

// ===== app/controller/user.js - 用户控制器 =====
const Controller = require('egg').Controller;

class UserController extends Controller {
  async list() {
    const { ctx, service } = this;
    const users = await service.user.getList();
    ctx.body = users;
  }

  async create() {
    const { ctx, service } = this;
    const { name, email } = ctx.request.body;
    const user = await service.user.create({ name, email });
    ctx.status = 201;
    ctx.body = user;
  }
}

module.exports = UserController;

// ===== app/service/user.js - 服务层 =====
const Service = require('egg').Service;

class UserService extends Service {
  async getList() {
    // 模拟数据库查询
    return [
      { id: 1, name: '张三', email: 'zhangsan@example.com' },
      { id: 2, name: '李四', email: 'lisi@example.com' }
    ];
  }

  async create(data) {
    // 模拟创建用户
    return { id: Date.now(), ...data };
  }
}

module.exports = UserService;

//  优点：分层清晰（Controller/Service）、规范统一
//  问题：TypeScript 支持不佳、基于 CommonJS 规范

NestJS 核心优势：
│
├──  架构设计
│   ├── Angular 风格，前端开发者友好
│   ├── Spring 设计思想，后端架构完善
│   ├── 强制模块化，代码组织清晰
│   └── 依赖注入（DI），解耦彻底
│
├──  TypeScript 原生支持
│   ├── 类型安全，减少运行时错误
│   ├── 装饰器语法，代码简洁优雅
│   ├── IDE 友好，智能提示完善
│   └── 重构容易，维护成本低
│
├──  企业级特性
│   ├── 模块（Module）系统
│   ├── 控制器（Controller）路由
│   ├── 服务（Service）业务逻辑
│   ├── 管道（Pipe）数据验证
│   ├── 守卫（Guard）权限控制
│   ├── 拦截器（Interceptor）AOP
│   └── 过滤器（Filter）异常处理
│
├──  底层灵活
│   ├── 默认使用 Express
│   ├── 可替换为 Fastify（高性能）
│   └── 支持微服务、WebSocket、GraphQL
│
└──  生态与文档
    ├── 官方文档非常完善
    ├── 社区活跃，更新频繁
    ├── 官方模块丰富
    └── 企业级解决方案多

NestJS 架构灵感来源：
│
├── Angular（前端框架）
│   ├── 模块化设计
│   ├── 依赖注入系统
│   ├── 装饰器语法
│   └── 元编程思想
│
└── Spring（Java 后端框架）
    ├── IoC 容器
    ├── AOP 编程
    ├── 分层架构
    └── 企业级最佳实践

架构层次对比：
│
├── Express / Koa
│   └── 仅实现 HTTP 服务
│       └── 需自己搭建：路由、日志、验证、分层
│
├── Egg.js
│   ├── 封装了 Koa
│   ├── 提供了 MVC 分层
│   ├── 但缺乏 TypeScript 支持
│   └── 架构灵活性不足
│
└── NestJS
    ├── 完整的架构体系
    ├── TypeScript 原生支持
    ├── DI + AOP + 装饰器
    ├── 底层可替换（Express/Fastify）
    └── 开箱即用的企业级特性

// ===== Express 实现 =====
const express = require('express');
const app = express();

app.use(express.json());

//  问题：路由、验证、业务逻辑混在一起
app.get('/users', (req, res) => {
  // 数据库查询逻辑
  const users = [{ id: 1, name: '张三' }];
  res.json(users);
});

app.post('/users', (req, res) => {
  const { name, email } = req.body;
  
  //  验证逻辑混在控制器中
  if (!name || !email) {
    return res.status(400).json({ error: '参数错误' });
  }
  
  //  业务逻辑混在控制器中
  const newUser = { id: Date.now(), name, email };
  res.status(201).json(newUser);
});

app.listen(3000);

// 问题总结：
// 1. 无分层架构
// 2. 无依赖注入
// 3. 无类型检查
// 4. 代码耦合严重

// ===== Koa 实现 =====
const Koa = require('koa');
const Router = require('koa-router');
const bodyParser = require('koa-bodyparser');

const app = new Koa();
const router = new Router();

app.use(bodyParser());

//  问题：比 Express 更优雅，但仍然缺乏架构
router.get('/users', async (ctx) => {
  const users = [{ id: 1, name: '张三' }];
  ctx.body = users;
});

router.post('/users', async (ctx) => {
  const { name, email } = ctx.request.body;
  
  //  验证逻辑手动实现
  if (!name || !email) {
    ctx.status = 400;
    ctx.body = { error: '参数错误' };
    return;
  }
  
  const newUser = { id: Date.now(), name, email };
  ctx.status = 201;
  ctx.body = newUser;
});

app.use(router.routes());
app.listen(3000);

// 优点：async/await 优雅
// 问题：架构需自己搭建

// ===== Egg.js 实现 =====

// app/router.js
module.exports = app => {
  const { router, controller } = app;
  router.get('/users', controller.user.list);
  router.post('/users', controller.user.create);
};

// app/controller/user.js
const Controller = require('egg').Controller;

class UserController extends Controller {
  async list() {
    const { ctx, service } = this;
    const users = await service.user.getList();
    ctx.body = users;
  }

  async create() {
    const { ctx, service } = this;
    const { name, email } = ctx.request.body;
    
    //  验证需手动实现或使用插件
    if (!name || !email) {
      ctx.status = 400;
      ctx.body = { error: '参数错误' };
      return;
    }
    
    const user = await service.user.create({ name, email });
    ctx.status = 201;
    ctx.body = user;
  }
}

module.exports = UserController;

// app/service/user.js
const Service = require('egg').Service;

class UserService extends Service {
  async getList() {
    return [{ id: 1, name: '张三' }];
  }

  async create(data) {
    return { id: Date.now(), ...data };
  }
}

module.exports = UserService;

// 优点：分层清晰（Controller/Service）
// 问题：TypeScript 支持不佳

// ===== NestJS 实现 =====

// src/main.ts - 入口文件
import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  // 全局验证管道
  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    transform: true,
  }));
  
  await app.listen(3000);
}
bootstrap();

// src/app.module.ts - 根模块
import { Module } from '@nestjs/common';
import { UsersModule } from './users/users.module';

@Module({
  imports: [UsersModule],
})
export class AppModule {}

// src/users/users.module.ts - 用户模块
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

// src/users/dto/create-user.dto.ts - 数据传输对象
import { IsString, IsEmail, IsInt, Min, Max, IsNotEmpty } from 'class-validator';

export class CreateUserDto {
  @IsString({ message: 'name 必须是字符串' })
  @IsNotEmpty({ message: 'name 不能为空' })
  name: string;

  @IsEmail({}, { message: 'email 格式不正确' })
  @IsNotEmpty({ message: 'email 不能为空' })
  email: string;

  @IsInt({ message: 'age 必须是整数' })
  @Min(0, { message: 'age 不能小于 0' })
  @Max(150, { message: 'age 不能大于 150' })
  age?: number;
}

// src/users/users.controller.ts - 控制器
import { Controller, Get, Post, Body, Param, ParseIntPipe } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';

@Controller('users')
export class UsersController {
  //  依赖注入：自动注入 UsersService
  constructor(private readonly usersService: UsersService) {}

  @Get()
  findAll(): Promise<User[]> {
    return this.usersService.findAll();
  }

  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number): Promise<User> {
    return this.usersService.findOne(id);
  }

  @Post()
  create(@Body() createUserDto: CreateUserDto): Promise<User> {
    //  自动验证：ValidationPipe 会自动验证 DTO
    return this.usersService.create(createUserDto);
  }
}

// src/users/users.service.ts - 服务
import { Injectable, NotFoundException } from '@nestjs/common';
import { CreateUserDto } from './dto/create-user.dto';

export interface User {
  id: number;
  name: string;
  email: string;
  age?: number;
}

@Injectable()
export class UsersService {
  private users: User[] = [
    { id: 1, name: '张三', email: 'zhangsan@example.com', age: 25 },
  ];

  findAll(): User[] {
    return this.users;
  }

  findOne(id: number): User {
    const user = this.users.find(u => u.id === id);
    if (!user) {
      throw new NotFoundException(`User with id ${id} not found`);
    }
    return user;
  }

  create(createUserDto: CreateUserDto): User {
    const newUser: User = {
      id: Date.now(),
      ...createUserDto,
    };
    this.users.push(newUser);
    return newUser;
  }
}

// ===== 优势总结 =====
//  1. 类型安全：TypeScript 完整类型检查
//  2. 自动验证：ValidationPipe + class-validator
//  3. 依赖注入：自动管理依赖关系
//  4. 分层清晰：Controller/Service/DTO 分离
//  5. 装饰器语法：代码简洁优雅
//  6. 异常处理：统一异常过滤器
//  7. 管道转换：ParseIntPipe 自动转换参数类型

// ===== 依赖注入原理 =====

//  传统方式：手动创建依赖
class UserController {
  private userService: UserService;
  
  constructor() {
    // 手动实例化，紧耦合
    this.userService = new UserService();
  }
}

//  NestJS 方式：依赖注入
@Controller('users')
export class UsersController {
  // 自动注入，松耦合
  constructor(private readonly usersService: UsersService) {}
  
  @Get()
  findAll() {
    return this.usersService.findAll();
  }
}

// ===== 依赖注入的优势 =====
// 1. 松耦合：Controller 不依赖具体的 Service 实现
// 2. 易测试：可以轻松 mock Service 进行单元测试
// 3. 易维护：修改 Service 实现不影响 Controller
// 4. 易扩展：可以轻松替换实现（如切换数据库）

// ===== 高级用法：自定义 Provider =====
@Module({
  providers: [
    // 方式1：标准写法
    {
      provide: 'USER_SERVICE',
      useClass: UsersService,
    },
    
    // 方式2：使用值
    {
      provide: 'CONFIG',
      useValue: { db: 'mysql', port: 3000 },
    },
    
    // 方式3：使用工厂函数
    {
      provide: 'CONNECTION',
      useFactory: (configService: ConfigService) => {
        // 注意：createConnection 是 TypeORM 0.2.x 旧 API，0.3+ 已移除，
        // 现行写法为 new DataSource(configService.dbConfig).initialize()
        return createConnection(configService.dbConfig);
      },
      inject: [ConfigService],
    },
  ],
})
export class AppModule {}

// 使用自定义 Provider
@Controller('users')
export class UsersController {
  constructor(
    @Inject('USER_SERVICE') private usersService: UsersService,
    @Inject('CONFIG') private config: any,
  ) {}
}

// ===== 内置管道 =====
import { 
  PipeTransform, 
  Injectable, 
  ArgumentMetadata,
  ParseIntPipe,
  ValidationPipe,
} from '@nestjs/common';

// 1. ParseIntPipe - 参数类型转换
@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {
  // id 自动转换为 number 类型
  return this.usersService.findOne(id);
}

// 2. ValidationPipe - 数据验证
// 全局启用
app.useGlobalPipes(new ValidationPipe());

// ===== 自定义管道 =====
// 注意：不能命名为 ValidationPipe，会与上面从 @nestjs/common 导入的内置管道重名冲突
import { BadRequestException } from '@nestjs/common';

@Injectable()
export class SimpleValidationPipe implements PipeTransform {
  transform(value: any, metadata: ArgumentMetadata) {
    // 验证逻辑
    if (!value) {
      throw new BadRequestException('Validation failed');
    }
    return value;
  }
}

// ===== 使用 class-validator 进行验证 =====
// 安装：pnpm add class-validator class-transformer

import { IsString, IsEmail, IsInt, Min, Max } from 'class-validator';

export class CreateUserDto {
  @IsString()
  name: string;

  @IsEmail()
  email: string;

  @IsInt()
  @Min(0)
  @Max(150)
  age: number;
}

// Controller 中使用
@Post()
create(@Body() createUserDto: CreateUserDto) {
  // ValidationPipe 会自动验证
  return this.usersService.create(createUserDto);
}

// ===== 守卫示例：JWT 认证 =====
import { 
  Injectable, 
  CanActivate, 
  ExecutionContext,
  UnauthorizedException,
} from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';

@Injectable()
export class AuthGuard implements CanActivate {
  constructor(private jwtService: JwtService) {}

  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const token = request.headers.authorization?.split(' ')[1];
    
    if (!token) {
      throw new UnauthorizedException('未登录');
    }
    
    try {
      const payload = this.jwtService.verify(token);
      request.user = payload;
      return true;
    } catch (error) {
      throw new UnauthorizedException('token 无效');
    }
  }
}

// 使用守卫
@Controller('users')
@UseGuards(AuthGuard)  // 整个控制器启用
export class UsersController {
  
  @Get('profile')
  getProfile(@Request() req) {
    return req.user;  // 守卫中注入的用户信息
  }
}

// ===== 拦截器示例：日志记录 =====
import { 
  Injectable, 
  NestInterceptor, 
  ExecutionContext, 
  CallHandler,
  Logger,
} from '@nestjs/common';
import { Observable, tap } from 'rxjs';
@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  private readonly logger = new Logger(LoggingInterceptor.name);

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const { method, url } = request;
    const now = Date.now();

    return next
      .handle()
      .pipe(
        tap(() => {
          this.logger.log(
            `${method} ${url} - ${Date.now() - now}ms`
          );
        }),
      );
  }
}

// 使用拦截器
@Controller('users')
@UseInterceptors(LoggingInterceptor)
export class UsersController {
  // 所有请求都会记录日志
}

// 默认使用 Express
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

// 切换为 Fastify
import { NestFactory } from '@nestjs/core';
import {
  FastifyAdapter,
  NestFastifyApplication,
} from '@nestjs/platform-fastify';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter(),
  );
  await app.listen(3000);
}
bootstrap();

// Fastify 性能对比：
// - Express：~10k req/s
// - Fastify：~30k req/s
// 性能提升：3倍左右

NestJS 底层架构：
│
├── HTTP 适配器层（可替换）
│   ├── ExpressAdapter（默认）
│   │   ├── 生态丰富
│   │   ├── 文档完善
│   │   └── 性能良好
│   │
│   └── FastifyAdapter（高性能）
│       ├── 性能卓越（3倍 Express）
│       ├── 生态略小
│       └── 官方推荐生产环境
│
└── NestJS 核心层（不变）
    ├── 模块系统
    ├── 依赖注入
    ├── 管道/守卫/拦截器
    └── 所有功能不受影响

项目选型决策：
│
├── 小型项目 / 个人项目
│   ├── 快速原型 → Express
│   ├── 学习入门 → Express / Koa
│   └── 高性能需求 → Koa + Fastify
│
├── 中型项目 / 团队项目
│   ├── 国内团队 → Egg.js
│   ├── TypeScript 技术栈 → NestJS
│   └── 快速开发 → Egg.js / NestJS
│
└── 大型项目 / 企业项目
    ├── 微服务架构 → NestJS
    ├── GraphQL API → NestJS
    ├── 长期维护 → NestJS
    └── 团队规范统一 → NestJS

NestJS 最佳实践场景：
│
├──  企业级应用
│   ├── 中大型项目
│   ├── 长期维护项目
│   └── 团队协作项目
│
├──  特定架构需求
│   ├── 微服务架构
│   ├── GraphQL API
│   ├── WebSocket 应用
│   └── RESTful API
│
├──  团队背景
│   ├── 前端团队为主
│   ├── Angular 技术栈
│   ├── TypeScript 技术栈
│   └── 全栈开发团队
│
└──  业务特点
    ├── 业务逻辑复杂
    ├── 需要良好的架构设计
    ├── 需要完善的权限控制
    └── 需要统一代码规范

学习路径建议：
│
├──  阶段一：Express/Koa 基础（1 周）
│   ├── 理解中间件机制
│   ├── 掌握路由设计
│   └── 了解 Web 框架原理
│
├──  阶段二：TypeScript 进阶（1 周）
│   ├── 装饰器语法
│   ├── 泛型编程
│   └── 元数据反射
│
├──  阶段三：NestJS 核心（2-3 周）
│   ├── 模块系统
│   ├── 依赖注入
│   ├── 管道/守卫/拦截器
│   └── 数据库集成
│
└──  阶段四：实战项目（3-4 周）
    ├── RESTful API 开发
    ├── 用户认证授权
    ├── 微服务架构
    └── 性能优化

// ===== Express =====
app.get('/users', (req, res) => { res.json(users); });

// ===== Koa =====
router.get('/users', async (ctx) => { ctx.body = users; });

// ===== Egg.js =====
router.get('/users', controller.user.list);

// ===== NestJS =====
@Controller('users')
export class UsersController {
  @Get() findAll() { return this.usersService.findAll(); }
}

// ===== Express =====
app.use((req, res, next) => { next(); });

// ===== Koa =====
app.use(async (ctx, next) => { await next(); });

// ===== NestJS =====
@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    next();
  }
}